﻿// <copyright file="IDialogBackend.cs" company="Microsoft Corporation">
// Copyright (c) Microsoft Corporation. All rights reserved.
//  Licensed under the MIT License.
// </copyright>

namespace Mva.Recognition
{
    using System;
    using System.Threading.Tasks;

    /// <summary>
    /// Describes the contract for dialog backends responsible for servicing general conversational
    /// state updates and providing responses from an assistant implementation.
    /// </summary>
    public interface IDialogBackend
        : IDisposable
    {
        /// <summary>
        /// Raised when an intermediate stage of keyword recognition or verification has been
        /// performed by the backend. Assistant implementations may choose to take staged user-
        /// perceivable action across multiple layers of confirmation or ignore intermediate stages
        /// and act only on the final, fully-confirmed recognition.
        /// </summary>
        event Action<string> KeywordRecognizing;

        /// <summary>
        /// Raised when the final keyword recognition step has been performed by the backend. An
        /// accepted result at this stage is full confirmation that user-perceived action, like
        /// showing a window and playing an earcon, is appropriate.
        /// </summary>
        event Action<string> KeywordRecognized;

        /// <summary>
        /// Raised when the backend produces an intermediate "hypothesis" for the ongoing speech-
        /// to-text it's currently performing. These results can change as the user continues
        /// speaking and the use of the text should be limited to low-error-impact utilization like
        /// a responsive visualization of what's being spoken.
        /// </summary>
        event Action<string> SpeechRecognizing;

        /// <summary>
        /// Raised when the backend produces its final speech-to-text result for a user utterance.
        /// This is the same text provided to the assistant implementation for business logic
        /// processing and can be considered as necessary for further client-side actions.
        /// </summary>
        event Action<string> SpeechRecognized;

        /// <summary>
        /// Raised when the backend provides information about an error encountered during the
        /// servicing of a request.
        /// </summary>
        event Action<DialogErrorInformation> ErrorReceived;

        /// <summary>
        /// Sets the object used as an audio source for this backend and clears any existing
        /// state in a previous source as needed.
        /// </summary>
        /// <param name="source"> The IDialogAudioInputProvider used as an audio source to this backend. </param>
        void SetAudioSource(IDialogAudioInputProvider source);

        /// <summary>
        /// Instructs a backend to perform any needed preliminary initialization before which it
        /// cannot handle requests.
        /// </summary>
        /// <returns> A task that completes once the backend is in a ready state. </returns>
        Task InitializeAsync();

        /// <summary>
        /// Instructs the turn to begin a turn based on the input available in the current input
        /// audio source. Validates for the presence of a keyword if provided a confirmation
        /// model resource to use.
        /// </summary>
        /// <param name="performConfirmation">
        ///     Whether to use the backend-specific model resource for validating the presence of
        ///     a keyword in the input audio stream, if available. If unavailable or false,
        ///     no verification will be attempted and the input audio will be treated as
        ///     previously-confirmed.
        /// </param>
        /// <returns> A task that completes when the turn has begun and audio is flowing. </returns>
        Task StartAudioTurnAsync(bool performConfirmation);

        void StopAudioTurn();
    }
}
